☁️ Loving our new documentation website? Provide feedback in the CloudCannon Community! ✨

values[*]

Table of contents

Description:

This key represents a single value option within a structure, defining the data format and appearance for content editors.

Appears in:
└── Structure
    └── values
        └── [*]
Type:
Object
Properties:
defaultboolean#

This key toggles whether CloudCannon should treat an entry in the values array as the default option for your Object or Array input.

Setting this key to true will mark this entry as the default option for your Object or Array input. If multiple entries in the values array are set to true, CloudCannon will use the first entry. If CloudCannon cannot determine the type of an entry within the values array based on the id_key or matching inputs across values[*].value objects, it will fall back to the default entry.

Defaults to: false

Show examplesHide examples

In this example, we want the entry labelled Employee to be our default option for populating inputs configured with the staff Structure.

Copied to clipboard
_structures:
  staff:
    style: modal
    values:
      - label: Employee
        default: true
        value:
          name: 
          job_description: 
          profile_picture: 
      - label: Manager
        value:
          name: 
          job_description: 
          profile_picture: 
          url:
{
  "_structures": {
    "staff": {
      "style": "modal",
      "values": [
        {
          "label": "Employee",
          "default": true,
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null
          }
        },
        {
          "label": "Manager",
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          }
        }
      ]
    }
  }
}

This key defines short descriptive text for editors shown in the Data Editor for expanded values matching this Structure value.

Has no default.

Supports a limited set of Markdown: links, bold, italic, subscript, superscript, and inline code elements are allowed.

This key defines the documentation link at the top of a Collection browser.

Collection documentation is useful for assisting your team members.

Show examplesHide examples

In this example, the documentation link for the data Collection goes to CloudCannon Documentation.

Copied to clipboard
collections_config:
  data:
    documentation:
      url: https://cloudcannon.com/documentation/
      text: CloudCannon Documentation
      icon: star
{
  "collections_config": {
    "data": {
      "documentation": {
        "url": "https://cloudcannon.com/documentation/",
        "text": "CloudCannon Documentation",
        "icon": "star"
      }
    }
  }
}

This key defines the order and custom grouping for inputs within a Structure.

The value is an array of group objects. Each group object can contain a heading, comment, collapsed, and inputs array.

Show examplesHide examples

In this example, we want to separate the inputs into two groups with descriptive headings: title and subtitle under the Titles heading, and author under the Details heading.

Copied to clipboard
_structures:
  article_information:
    values:
      - label: Blog
        value:
          title: 
          subtitle: 
          author: 
        groups:
          - heading: Titles
            inputs:
              - title
              - subtitle
          - heading: Details
            inputs:
              - author
{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "value": {
            "title": null,
            "subtitle": null,
            "author": null
          },
          "groups": [
            {
              "heading": "Titles",
              "inputs": [
                "title",
                "subtitle"
              ]
            },
            {
              "heading": "Details",
              "inputs": [
                "author"
              ]
            }
          ]
        }
      ]
    }
  }
}

This key toggles whether CloudCannon will hide inputs that are not present in a given value from a Structure from the Data Editor.

Setting this key to true will hide inputs that are not present in a given value from a Structure from the Data Editor. Hiding these inputs does not delete the data. You can see non-structure data keys by opening a file in the Source Editor. This key has no effect if remove_extra_inputs is true.

You can also configure this behavior for all values of a Structure using hide_extra_inputs inside _structures.*.

Defaults to: false

iconstring#

This key defines an icon used when displaying the structure (defaults to either format_list_bulleted for items in arrays, or notes otherwise).

Allowed values: 123 360 10k 10mp 11mp 12mp 13mp 14mp 15mp 16mp and 3574 more.

Show examplesHide examples

In this example, CloudCannon will display the article icon for the entry labeled Blog in the article_information Structure.

Copied to clipboard
_structures:
  article_information:
    values:
      - label: Blog
        icon: article
{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "icon": "article"
        }
      ]
    }
  }
}
idstring#

This key defines the string used to identify a given Structure value when refering to it from other input configuration.

Show examplesHide examples

In this example, we have configured the blog_post ID for the entry labeled Blog in the article_information Structure.

Copied to clipboard
_structures:
  article_information:
    values:
      - label: Blog
        id: blog_post
{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "id": "blog_post"
        }
      ]
    }
  }
}
imagestring#

This key defines the path to an image in your source files used when displaying the structure value.

Can be either a source (has priority) or output path.

Show examplesHide examples

In this example, we have configured the /images/blog-icon.png image for the entry labeled Blog in the article_information Structure.

Copied to clipboard
_structures:
  article_information:
    values:
      - label: Blog
        image: /images/blog-icon.png
{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "image": "/images/blog-icon.png"
        }
      ]
    }
  }
}

This key defines which inputs are available at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.

Show examplesHide examples

In this example, we have configured the date_created key as a Date and Time Input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.

Copied to clipboard
_inputs:
  date_created:
    type: datetime
    label: Date of article creation
    comment: UTC +0 timezone
    context:
      open: false
      title: Help
      icon: help
      content: This date field will automatically populate when you create an article.
    hidden: false
    disabled: true
    instance_value: NOW
    cascade: true
    options:
      timezone: Etc/UTC
{
  "_inputs": {
    "date_created": {
      "type": "datetime",
      "label": "Date of article creation",
      "comment": "UTC +0 timezone",
      "context": {
        "open": false,
        "title": "Help",
        "icon": "help",
        "content": "This date field will automatically populate when you create an article."
      },
      "hidden": false,
      "disabled": true,
      "instance_value": "NOW",
      "cascade": true,
      "options": {
        "timezone": "Etc/UTC"
      }
    }
  }
}

In this example, we have configured the blog_tags key as a Multiselect Input in the blog Collection.

Copied to clipboard
collections_config:
  blog:
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values:
            - Opinion
            - Feature
            - Resource
{
  "collections_config": {
    "blog": {
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": [
              "Opinion",
              "Feature",
              "Resource"
            ]
          }
        }
      }
    }
  }
}

This key defines globs that filter which files CloudCannon should use for Input configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.inputs.yml.

You can use this key anywhere you would use the _inputs key in the configuration cascade.

This key has no default.

Show examplesHide examples

In this example, we have several Input Configuration Files in the .cloudcannon/inputs/ folder, with each file containing multiple Input definitions. The value of the _inputs_from_glob key tells CloudCannon to only use the seo.cloudcannon.inputs.yml and blog-details.cloudcannon.inputs.yml files in that folder.

Copied to clipboard
collections_config:
  posts:
    path: content/posts
    icon: event
    inputs_from_glob:
      - /.cloudcannon/inputs/seo.cloudcannon.inputs.yml
      - /.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml
{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "icon": "event",
      "inputs_from_glob": [
        "/.cloudcannon/inputs/seo.cloudcannon.inputs.yml",
        "/.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml"
      ]
    }
  }
}
Copied to clipboard
seo_title:
  type: text
  options:
    required: true
    max_length: 50
seo_description:
  type: textarea
  options:
    show_count: true
    required: true
    max_length: 125
seo_image:
  type: image
  options:
    path:
      uploads: images
    accepts_mime_types:
      - image/png
      - image/jpeg
    required: true
    pattern: (?i)\.(jpe?g|png)$
    pattern_message: Please select a JPG or PNG image file
{
  "seo_title": {
    "type": "text",
    "options": {
      "required": true,
      "max_length": 50
    }
  },
  "seo_description": {
    "type": "textarea",
    "options": {
      "show_count": true,
      "required": true,
      "max_length": 125
    }
  },
  "seo_image": {
    "type": "image",
    "options": {
      "path": {
        "uploads": "images"
      },
      "accepts_mime_types": [
        "image/png",
        "image/jpeg"
      ],
      "required": true,
      "pattern": "(?i)\\.(jpe?g|png)$",
      "pattern_message": "Please select a JPG or PNG image file"
    }
  }
}
labelstring#

This key defines the display name for a given value in a Structure.

The name will appear in the + Add button dropdown below an Object or Array input or in the Structures modal (if configured).

By default, this key falls back to unknown.

Show examplesHide examples

In this example, we want two value options for our staff structure: one called Manager and one called Employee.

Copied to clipboard
_structures:
  staff:
    values:
      - label: Employee
        value:
          name: 
          job_description: 
          profile_picture: 
      - label: Manager
        value:
          name: 
          job_description: 
          profile_picture: 
          url:
{
  "_structures": {
    "staff": {
      "values": [
        {
          "label": "Employee",
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null
          }
        },
        {
          "label": "Manager",
          "value": {
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          }
        }
      ]
    }
  }
}

This key defines the appearance of a Card when choosing an item to create. This uses preview as a base, and keys inside this object are overrides.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Show examplesHide examples

In this example, we have configured the appearance of Cards in inputs using the Structure staff when adding items.

Copied to clipboard
_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        picker_preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        picker_preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

This key defines which order input groups and ungrouped inputs appear in.

Defaults to: false

previewObject#

This key defines the appearance of a Card.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Show examplesHide examples

In this example, we have configured the appearance of file Cards in the Collection browser.

Copied to clipboard
collections_config:
  blog:
    preview:
      text:
        - key: title
      subtext:
        - key: author
      icon: edit_note
      icon_color:
        - key: color
        - '#ff0000'
      image:
        - key: image
      metadata:
        - template:
            - url
        - icon: event
          text:
            - template: Published on {date|date_long}
      gallery:
        - key: featured_image
{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ],
        "subtext": [
          {
            "key": "author"
          }
        ],
        "icon": "edit_note",
        "icon_color": [
          {
            "key": "color"
          },
          "#ff0000"
        ],
        "image": [
          {
            "key": "image"
          }
        ],
        "metadata": [
          {
            "template": [
              "url"
            ]
          },
          {
            "icon": "event",
            "text": [
              {
                "template": "Published on {date|date_long}"
              }
            ]
          }
        ],
        "gallery": [
          {
            "key": "featured_image"
          }
        ]
      }
    }
  }
}

In this example, we have configured the appearance of Cards in inputs using the Structure staff.

Copied to clipboard
_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

This key toggles whether CloudCannon will remove empty nested inputs from an Object Input or Array Input using a given value from a Structure before persisting them to your file.

Setting this key to true will remove empty nested inputs from an Object Input or Array Input using a given value from a Structure before persisting them to your file. CloudCannon considers an input to be empty when its value is null, ' ', or undefined. If this key is true, empty inputs will be visible in the Data Editor but not the Source Editor. For this key to function, you must also configure id_key for the Structure, as removing inputs prevents CloudCannon from comparing Structure values.

You can also configure this behavior for all values of a Structure using remove_empty_inputs inside _structures.*.

Defaults to: false

This key toggles whether CloudCannon will remove inputs that are not present in a given value from a Structure from a file before loading it in an Editing Interface.

Setting this key to true will remove inputs that are not present in a given value from a Structure from a file before loading it in an Editing Interface. Non-Structure inputs will not be visible in the Visual Editor, Content Editor, or Data Editor, and saving the file will remove them from the file before persisting the changes to your Git repository.

You can also configure this behavior for all values of a Structure using remove_extra_inputs inside _structures.*.

Defaults to: true

This key toggles whether CloudCannon will reorder inputs in a file to match the order defined in a given value from a Structure.

Setting this key to false will preserve the existing order of inputs in a file, regardless of the order defined in the Structure value.

By default, this key is true (i.e., inputs are reordered to match the Structure value).

You can also configure this behavior for all values of a Structure using reorder_inputs inside _structures.*.

Defaults to: true

This key defines defines fixed data sets to populate Select and Multiselect inputs at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _select_data will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on Select and Multiselect inputs.

Show examplesHide examples

In this example, we have configured the blog_tags Multiselect input for the blog Collection.

Copied to clipboard
collections_config:
  blog:
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource
{
  "collections_config": {
    "blog": {
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      }
    }
  }
}

This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _structures will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on structures.

Show examplesHide examples

In this example, we want to populate an Array input in the blog Collection with Related Articles, including the name, description, and url fields.

Copied to clipboard
collections_config:
  blog:
    _structures:
      related_articles:
        style: select
        values:
          - preview:
              text:
                - key: name
              subtext:
                - key: url
            value:
              name: 
              description: 
              url:
{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "style": "select",
          "values": [
            {
              "preview": {
                "text": [
                  {
                    "key": "name"
                  }
                ],
                "subtext": [
                  {
                    "key": "url"
                  }
                ]
              },
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

In this example, we want to populate an Array input with Staff members, including the name, job_description, and profile_picture fields for all staff types, and the url field for Managers only.

Copied to clipboard
_structures:
  staff:
    style: modal
    hide_extra_inputs: false
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "style": "modal",
      "hide_extra_inputs": false,
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

This key defines globs that filter which files CloudCannon should use for Structure configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source) and must end in the file extension .cloudcannon.structures.yml.

You can use this key anywhere you would use the _structures key in the configuration cascade.

Please see our documentation on values_from_glob for defining individual Structure values in a split Configuration File.

This key has no default.

Show examplesHide examples

In this example, we have several Structure Configuration Files in the .cloudcannon/structures/ folder. The value of the _structures_from_glob key tells CloudCannon to use the staffMembers.cloudcannon.structures.yml file in that folder.

Copied to clipboard
_structures_from_glob:
  - /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml
{
  "_structures_from_glob": [
    "/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml"
  ]
}
Copied to clipboard
staff:
  style: modal
  values:
    - label: Employee
      value:
        name: 
        job_description: 
        profile_picture: 
    - label: Manager
      value:
        name: 
        job_description: 
        profile_picture: 
        url:
{
  "staff": {
    "style": "modal",
    "values": [
      {
        "label": "Employee",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null
        }
      },
      {
        "label": "Manager",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null,
          "url": null
        }
      }
    ]
  }
}
tabbedboolean#

This key toggles whether CloudCannon should create tabs in the Data Editor if you have two layers of nested object within your Structure.

Setting this key to true will create tabs in the Data Editor for two layers of nested objects within your Structure.

By default, this key is false (i.e., Object and Array inputs using this Structure option are not tabbed).

Defaults to: false

Show examplesHide examples

In this example, we want the content and style keys in our Structure to be tabs at the top of the Data Editor, with the title and text, and color and font keys nested within those tabs respectively.

Copied to clipboard
_structures:
  components:
    values:
      - label: Component
        tabbed: true
        value:
          content:
            title: 
            text: 
          style:
            color: 
            font:
{
  "_structures": {
    "components": {
      "values": [
        {
          "label": "Component",
          "tabbed": true,
          "value": {
            "content": {
              "title": null,
              "text": null
            },
            "style": {
              "color": null,
              "font": null
            }
          }
        }
      ]
    }
  }
}

This key defines which tags are associated with a given value in a Structure.

You can use tags to group and filter Structure options when selecting from a modal.

This key has no default.

Show examplesHide examples

In this example we have three options for the page_components Structure: Hero Component, Feature Component, and Video Component. We can search the Structure modal using the image, text, button, and video tags to filter Structure values.

Copied to clipboard
_structures:
  page_components:
    style: modal
    values:
      - label: Hero Component
        tags:
          - image
          - text
        value:
          title: 
          description: 
          image_path: 
          link:
            text: 
            url: 
      - label: Feature Component
        tags:
          - image
          - text
          - button
        value:
          image_path: 
          title: 
          description: 
          button:
            link: 
            text: 
          reversed_layout: false
      - label: Video Component
        tags:
          - image
          - video
        value:
          image_path: 
          videoUrl:
{
  "_structures": {
    "page_components": {
      "style": "modal",
      "values": [
        {
          "label": "Hero Component",
          "tags": [
            "image",
            "text"
          ],
          "value": {
            "title": null,
            "description": null,
            "image_path": null,
            "link": {
              "text": null,
              "url": null
            }
          }
        },
        {
          "label": "Feature Component",
          "tags": [
            "image",
            "text",
            "button"
          ],
          "value": {
            "image_path": null,
            "title": null,
            "description": null,
            "button": {
              "link": null,
              "text": null
            },
            "reversed_layout": false
          }
        },
        {
          "label": "Video Component",
          "tags": [
            "image",
            "video"
          ],
          "value": {
            "image_path": null,
            "videoUrl": null
          }
        }
      ]
    }
  }
}
valuevalue Required#

This key defines which nested inputs the Structure value should add to an Object or Array input.

You must define this key for the Structure value to function.

Nested keys can be any input you require in your Object or Array.

For more information, please read our documentation on configuring an Object input and configuring and Array input.

Show examplesHide examples

In this example we want to populate the details Object input with the nested keys title, subtitle, and author we have defined under the values.value key.

Copied to clipboard
_structures:
  article_information:
    values:
      - label: Blog
        value:
          title: 
          subtitle: 
          author: 
_inputs:
  details:
    type: object
    options:
      structures: _structures.article_information
{
  "_structures": {
    "article_information": {
      "values": [
        {
          "label": "Blog",
          "value": {
            "title": null,
            "subtitle": null,
            "author": null
          }
        }
      ]
    }
  },
  "_inputs": {
    "details": {
      "type": "object",
      "options": {
        "structures": "_structures.article_information"
      }
    }
  }
}
Examples:
Open in a new tab